home *** CD-ROM | disk | FTP | other *** search
/ SPACE 1 / SPACE - Library 1 - Volume 1.iso / program / 569 / gemfst17 / gemutil.doc < prev    next >
Text File  |  1992-06-01  |  29KB  |  559 lines
  1.  
  2. **************************************************************************
  3. *
  4. * GEMUTIL.DOC - Descriptions of the utility functions in GEMFAST.
  5. *
  6. *  05/26/90 - v1.4
  7. *             The rsc_gstrings()/rsc_sstrings() routines now support ICONs.
  8. *
  9. *             The frm_dsdial() function has been added.
  10. *
  11. *  08/28/89 - v1.3
  12. *             Massive changes have been made to the utilty routines, and
  13. *             to this document.  Your best bet is to read the entire doc
  14. *             over again.
  15. *
  16. *             Most of the changes involve renaming routines to move toward
  17. *             a consistant naming standard (which is to pave the way for
  18. *             things planned for v2.0).  I've done my best to cover the
  19. *             name changes with #define statements in GEMFAST.H, so your
  20. *             existing code should work, but you should make every effort
  21. *             to convert existing and new code to the new names.  Sorry,
  22. *             I guess I wasn't thinking far enough ahead when I did the
  23. *             first release.
  24. *             
  25. *             For all the renamed routines, I've put the old name in
  26. *             the title bar of the new function's name.
  27. **************************************************************************
  28.  
  29. This document describes the functions in the AESUTxxx modules of the
  30. GEMFAST bindings.  These are not GEM function calls, and thus are not
  31. documented in standard GEM programming guides.
  32.  
  33. Within this document, the most changes will be indicated by a vertical bar 
  34. and the change level (|vX.X).
  35.  
  36. Definitions:
  37.  
  38. NO_OBJECT - A constant defined in GEMFAST.H; it has a value of -1.  This
  39.             value is used by most object-related utilties to indicate that
  40.             no object was found with the criteria specified in the search
  41.             (eg, for objc_find(), obj_rbfind(), etc).
  42.  
  43. GRECT     - A graphics-type rectangle of the form x,y,w,h.  A GRECT
  44.             describes a screen area by defining the x/y of the upper left
  45.             corner, and the width and height of the area.
  46.  
  47. VRECT     - A vdi-type rectangle of the form x1,y1,x2,y2.  A VRECT
  48.             describes a screen area by defining the upper left and lower
  49.             right corners of the area in x/y coordinates.
  50.  
  51. xRECT     - Used to indicate that either of the above types is accepted.
  52.  
  53. ;*************************************************************************
  54. ; Rectangle utilties.
  55. ;*************************************************************************
  56.  
  57. ;-------------------------------------------------------------------------
  58. ; rc_copy
  59. ;-------------------------------------------------------------------------
  60.  
  61. void rc_copy (xRECT *source, xRECT *dest)
  62.  
  63.         This function copies a rectangle.  It will copy either a GRECT or
  64.         VRECT type rectangle.  More generally, it will copy 2 longwords
  65.         from source to dest, they don't have to be rectangles at all.
  66.          >> NOTE BACKWARDS ORDER OF SOURCE & DEST.  Sorry, not my decision.
  67.  
  68. ;-------------------------------------------------------------------------
  69. ; rc_equal
  70. ;-------------------------------------------------------------------------
  71.  
  72. bool rc_equal(xRECT *rect1, xRECT *rect2)
  73.         
  74.         This function tests 2 rectangles for equality and returns TRUE/FALSE
  75.         (1/0) accordingly.  Works on GRECT or VRECT type rectangles, but
  76.         both rectangles must be of the same type.  More generally, this
  77.         function compare 2 sets of 2 contiguous longwords.
  78.  
  79. ;-------------------------------------------------------------------------
  80. ; rc_intersect
  81. ;-------------------------------------------------------------------------
  82.      
  83. bool rc_intersect(GRECT *rect1, GRECT *rect2)
  84.  
  85.         This function computes the intersection of 2 rectangles.  It works
  86.         only for GRECT type rectangles.  The intersection is the parts of 
  87.         two rectangles which overlap each other; this function is typically
  88.         used in processing the AES window-update rectangle list.  The result
  89.         is placed into 'rect2', overlaying the original data (again, not my
  90.         decision).  TRUE/FALSE is returned, depending on whether the 
  91.         rectangles had a common intersected area or not; the values in 
  92.         'rect2' are modified regardless of whether there was an intersection or not.
  93.         If the rectangle representing the intersecting area has a width or
  94.         height of zero, this routine will return TRUE.
  95.  
  96. ;-------------------------------------------------------------------------
  97. ; rc_union
  98. ;-------------------------------------------------------------------------
  99.  
  100. void rc_union(GRECT *rect1, GRECT *rect2)
  101.  
  102.         This function computes the union of two rectangles.  The union is 
  103.         the single rectangle that encompases all the area defined by the 
  104.         individual rectangles.  It works only for GRECT type rectangles.  
  105.         The result is placed into 'rect2'.
  106.  
  107. ;-------------------------------------------------------------------------
  108. ; rc_vtog
  109. ;-------------------------------------------------------------------------
  110.      
  111. void rc_vtog(VRECT *rect1, GRECT *rect2)
  112.  
  113.         This function converts a VRECT rectangle to a GRECT rectangle.
  114.         Do not specify the same rectangle for input and output.
  115.  
  116. ;-------------------------------------------------------------------------
  117. ; rc_gtov
  118. ;-------------------------------------------------------------------------
  119.         
  120. void rc_gtov(GRECT *rect1, VRECT *rect2)
  121.  
  122.         This function converts a GRECT rectangle to a VRECT rectangle.
  123.         Do not specify the same rectangle for input and output.
  124.  
  125. ;-------------------------------------------------------------------------
  126. ; rc_vadjust            (formerly objclv_adjust)
  127. ; rc_gadjust            (formerly objclg_adjust)
  128. ;-------------------------------------------------------------------------
  129.         
  130. void rc_vadjust(VRECT *rect, int h_adjust, int v_adjust);
  131. void rc_gadjust(GRECT *rect, int h_adjust, int v_adjust);
  132.  
  133.         These functions expand or contract a rectangle by a given amount
  134.         in each axis. A positive value exands the area, a negative
  135.         value contracts it.  You must use rc_gadjust for GRECTs and
  136.         rc_vadjust for VRECTs.  
  137.         
  138. |v1.3   Negative results are prevented by the adjust routines; zero will be 
  139. |       placed into any rectangle structure element which would have been 
  140. |       negative after the adjustment.
  141.         
  142. ;*************************************************************************
  143. ; Object utilities.
  144. ;*************************************************************************
  145.  
  146. ;-------------------------------------------------------------------------
  147. ; obj_flchange          (formerly objfl_change)
  148. ;-------------------------------------------------------------------------
  149.  
  150. void obj_flchange(OBJECT *tree, int object, int flagsmask, int updateflag);
  151.  
  152.         This function sets or resets bits in an object's ob_flags field.
  153.         Depending on the setting of 'updateflag' the object is updated 
  154.         on the screen or not. (Update is done via objc_draw internally).
  155.         If the high bit of 'flagsmask' is set, the flags bits are reset,
  156.         otherwise they are set.  This allows the following syntax:
  157.            objfl_change(mytree, myobj,  HIDETREE, TRUE);
  158.            objfl_change(mytree, myobj, ~HIDETREE, FALSE);
  159.         The first case will set 'myobj' to hidden and will erase it from
  160.         the screen.  The second case will set 'myobj' to visible, but does
  161.         not update the screen.
  162.         
  163.         Note that you CAN use this function to hide and unhide trees
  164.         visibly on the screen.  When the objc_draw is called internally
  165.         by this function, the draw starts at the root of the tree, but is
  166.         clipped by the x/y/w/h of the object who's state is being changed.
  167.         This means that a flag change to HIDETREE with update will draw
  168.         the parents of the hidden object, effectively erasing it on the
  169.         screen.  The same holds true for setting an object to ~HIDETREE;
  170.         the object will be redrawn and become visible.
  171.  
  172. |v1.4   Be aware that the xywh sizes of the changed object are used in the 
  173. |       internal objc_draw() when redraw is requested.  For window-oriented
  174. |       programs, where some of the object tree might be outside a window's
  175. |       work area, it is best for the calling program to request no redraw,
  176. |       and then to handle the redraw itself, specifying the window's work
  177. |       area as a clipping rectangle.  (This is not new for v1.4, it just
  178. |       hasn't been documented as such before.)
  179.         
  180. ;-------------------------------------------------------------------------
  181. ; obj_stchange          (formerly objst_change)
  182. ;-------------------------------------------------------------------------
  183.  
  184. void obj_stchange(OBJECT *tree, int object, int statemask, int updateflag);
  185.  
  186.         This function sets or resets bits in an object's ob_state field.
  187.         Depending on the setting of 'updateflag' the object is updated 
  188.         on the screen or not. (Update is done via objc_draw internally).
  189.         If the high bit of 'statemask' is set, the state bits are reset,
  190.         otherwise they are set.  This allows the following syntax:
  191.            objst_change(mytree, myobj,  SELECTED, TRUE);
  192.            objst_change(mytree, myobj, ~SELECTED, FALSE);
  193.         The first case will set 'myobj' to SELECTED and show it that way
  194.         on the screen.  The second case will set 'myobj' to non-selected,
  195.         and will not update the screen.
  196.  
  197. |v1.4   Be aware that the xywh sizes of the root object are used in the 
  198. |       internal objc_draw() when redraw is requested.  For window-oriented
  199. |       programs, where some of the object tree might be outside a window's
  200. |       work area, it is best for the calling program to request no redraw,
  201. |       and then to handle the redraw itself, specifying the window's work
  202. |       area as a clipping rectangle.  (This is not new for v1.4, it just
  203. |       hasn't been documented as such before.)
  204.         
  205. ;-------------------------------------------------------------------------
  206. ; obj_xywh              (formerly objc_xywh)
  207. ;-------------------------------------------------------------------------
  208.  
  209. void obj_xywh(OBJECT *tree, int object, GRECT *rect);
  210.  
  211.         Returns an object's x/y/w/h values into a GRECT rectangle.  Note
  212.         that the x/y values are NOT automatically adjusted to screen 
  213.         coordinates, they are copied directly from the object tree 
  214.         structure.  (Thus, if the object index is 0 (R_TREE) the rectangle 
  215.         will reflect screen coordinates, for any child object it will not.)
  216.  
  217. ;-------------------------------------------------------------------------
  218. ; obj_offxywh
  219. ;-------------------------------------------------------------------------
  220.  
  221. void obj_offxywh( OBJECT *tree, int object, GRECT *rect);
  222.  
  223.         Returns any object's screen-adjusted x/y/w/h values into a GRECT 
  224.         rectangle.  This is a shortcut to calling objc_offset() then
  225.         copying the object's w/h data into the GRECT structure.
  226.  
  227. ;-------------------------------------------------------------------------
  228. ; objcl_calc            (THIS ROUTINE IS BEING PHASED OUT!)
  229. ;-------------------------------------------------------------------------
  230.  
  231. void objcl_calc(OBJECT *tree, int object, {GRECT *r1|NULL}, {VRECT *r2|NULL});
  232.  
  233. |v1.3   THIS ROUTINE IS BEING PHASED OUT, DO NOT RELY ON IT!  It will be
  234. |       rewritten someday, but will have a new name (obj_clipcalc).
  235.  
  236.         This routine does clipping calculations for an object. It calculates
  237.         both GRECT and VRECT clipping rectangle simulataneously; if you
  238.         specify a null pointer for one of the rectangle types those values
  239.         won't be returned.  This function will handle OUTLINED and SHADOWED
  240.         objects, and will return the proper clipping rectangle to be passed
  241.         to objc_draw() or vs_clip().  Typical usage might be:
  242.          To redraw an object after changing ob_state or ob_flags...
  243.             objcl_calc(mytree, refreshobj, &cliprect, 0L);
  244.             objc_draw(mytree, refreshobj, MAX_DEPTH, cliprect);
  245.          To outline an object with a VDI rounded rectangle...  
  246.             objcl_calc(mytree, refreshobj, 0L, &boxrect);
  247.             v_rbox(vdi_handle, &boxrect);
  248.  
  249. ;-------------------------------------------------------------------------
  250. ; obj_rbfind            (formerly objxrb_which)
  251. ;-------------------------------------------------------------------------
  252.  
  253. int  obj_rbfind(OBJECT *tree, int parentobj, int state);
  254.  
  255.         This function returns the index of the first child object of the
  256.         specified parent which is in the desired state, or -1 if no child
  257.         objects are in that state.  Note that the state test is done via
  258.         bit-wise AND. As an example, it is possible to find an object which is
  259.         either SELECTED *OR* CROSSED, but it is not possible to limit the
  260.         search to only for objects which are *both* SELECTED *AND* CROSSED.
  261.  
  262. ;-------------------------------------------------------------------------
  263. ; objrb_which           (old name, which will be dropped eventualy)
  264. ; obj_rbwhich           (old name, which will be dropped eventualy)
  265. ;-------------------------------------------------------------------------
  266.  
  267. int  objrb_which(OBJECT *tree, int parentobj);
  268.  
  269.         This function returns the index of the first child object of the
  270.         specified parent which has the SELECTED bit set, or -1 if no child
  271.         objects are selected.  It is most useful in determining which 
  272. |v1.3   radio button in a group has been selected.  This function is
  273. |       supported via a #define in the GEMFAST.H file, and actually 
  274. |       generates a call to obj_rbfind(), passing a state of SELECTED.
  275. |
  276. |       This function is being phased out, it is recommended that you use
  277. |       obj_rbfind(tree, parent, SELECTED) to perform this function.
  278.  
  279. ;-------------------------------------------------------------------------
  280. ; obj_rbselect
  281. ;-------------------------------------------------------------------------
  282.  
  283. int  obj_rbselect(OBJECT *tree, int object, int state);
  284.  
  285.         This function logically de-selects the current object in a group
  286.         of radio buttons and selects the specified object.  The return 
  287.         value is the index of the object that was selected before the
  288.         function was called.  Rules for the 'state' value are as described
  289.         under the obj_rbfind function.
  290.         
  291.         This function can handle the situation where there is no object in
  292.         the radio button group which is currently selected; the new object
  293.         is set to the specified state.  This function *assumes* that the
  294.         new object is a radio button type object, and that all other objects
  295.         in the new object's parent are also radio button type objects.
  296.         This does not have to be the case, but the routine can break down
  297.         under extreme conditions (eg, don't try to specify the root as the
  298.         new object.)
  299.  
  300.         Note that this function DOES NOT REDRAW either of the objects
  301.         which are changed, it only changes the ob_state values in the
  302.         object array.  This function is primarily designed to pre-set
  303.         radio buttons to a known state before calling a dialog handler.
  304.         If redraw is needed as well, use a sequence such as:
  305.         
  306.             oldobj = obj_rbselect(ptree, newobj, SELECTED);
  307.             if (oldobj > R_TREE)       
  308.                 objc_draw(ptree, oldobj, MAX_DEPTH, cliprect);
  309.             objc_draw(ptree, newobj, MAX_DEPTH, cliprect);
  310.  
  311.         Alternatively, a single objc_draw() can be used, specifying the
  312.         parent of the radio button group.  (This works fine for small 
  313.         groups of radio buttons, but the speed of redraw can be a factor
  314.         for a large group of buttons.)
  315.         
  316. |v1.4   This function is new with this version.
  317.  
  318. ;-------------------------------------------------------------------------
  319. ; obj_parent
  320. ;-------------------------------------------------------------------------
  321.  
  322. int  obj_parent(OBJECT *tree, int curentobj);
  323.  
  324.         This function returns the index of the parent object of the
  325.         specified object.  By definition, the root object in a tree has
  326.         no parent, 0 will be returned (as if the root were its own parent).
  327.         This function is useful for things like building your own radio
  328.         button handler using evnt_multi().
  329.  
  330. ;-------------------------------------------------------------------------
  331. ; obj_xtfind
  332. ;-------------------------------------------------------------------------
  333.  
  334. int  obj_xtfind(OBJECT *tree, int parent, int xtype);
  335.  
  336.         This function returns the index of the child object within 'parent'
  337.         which has the specified extended object type.  The extended object
  338.         type is encoded within the high byte of the ob_type field, and is
  339.         useful for categorizing objects by function, or for connecting
  340.         objects to array elements by using the extended type as an index.
  341.         If no object with the given type is found, NO_OBJECT is returned.
  342.         
  343. |v1.4   This function is new with this release.  It is the functional 
  344. |       equivelent of the old find_exttype() routine from the 'canned
  345. |       source' library.
  346.  
  347. ;*************************************************************************
  348. ; Resource utilties.
  349. ;*************************************************************************
  350.  
  351. ;-------------------------------------------------------------------------
  352. ; rsc_sstrings
  353. ;-------------------------------------------------------------------------
  354.  
  355. void rsc_sstrings(OBJECT *tree, 
  356.                     int obj1,char *ptr1,
  357.                     [obj2,ptr2, ... objn,ptrn,]
  358.                     -1);
  359.                  
  360.         This function sets one or more string pointers within an object
  361.         tree.  It understands the difference between STRING, BUTTON, and
  362.         TEXT object types, and sets the appropriate pointer fields (ob_spec
  363.         or te_ptext).  Any number of object/pointer pairs may be specified,
  364.         the list is terminated by a negative object number.  The purpose
  365.         of this function is to replace all the lines of code looking like...
  366.             *((TEDINFO *)(tree[object].ob_spec))->te_ptext = pointer;
  367.         with the simpler construct...
  368.             rsc_strings(tree, str1obj,pstr1, 
  369.                               txt1obj,ptxt1, 
  370.                               /* etc */ 
  371.                               -1);
  372.  
  373. |v1.3   This routine understands objects with the INDIRECT flag set, and 
  374. |       will use the ob_spec field as an indirect pointer if appropriate.
  375. |v1.4   This routine now handles ICON objects.
  376.  
  377. ;-------------------------------------------------------------------------
  378. ; rsc_gstrings
  379. ;-------------------------------------------------------------------------
  380.  
  381. void rsc_gstrings(OBJECT *tree, 
  382.                     int obj1,char **ptr1,
  383.                     [obj2,**ptr2, ... objn,**ptrn,]
  384.                     -1);
  385.                  
  386.         This function gets one or more string pointers from within an object
  387.         tree.  It understands the difference between TEXT/nonTEXT object
  388.         types, and gets the appropriate fields (ob_spec or te_ptext). 
  389.         Any number of object/pointer pairs may be specified, the list is
  390.         terminated by a negative object number.  This is a provided as a 
  391.         shortcut to doing a long series of rsrc_gaddr() calls to get the
  392.         string/text pointers from a tree.  Note that this function is not
  393.         as flexible as rsrc_gaddr()...if the object type is one of the
  394.         text objects, it will return a te_ptext pointer, otherwise the
  395.         ob_spec value is returned.  When used with strings/text, the 
  396.         ob_spec field will be a string pointer.
  397.  
  398.           example() {
  399.           char *string1;
  400.           char *text2;
  401.                     
  402.           rsrc_gaddr(R_TREE, MYTREE, &mytree);
  403.           rsc_gstrings(mytree, MYSTR1,&string1,
  404.                                MYTXT2,&text2,
  405.                                -1);
  406.           }
  407.  
  408. |v1.3   This routine understands objects with the INDIRECT flag set, and 
  409. |       will use the ob_spec field as an indirect pointer if appropriate.
  410. |       Unlike previous releases, this routine has now been tested.
  411. |v1.4   This routine now understands ICON objects.
  412.         
  413. ;-------------------------------------------------------------------------
  414. ; rsc_treefix
  415. ;-------------------------------------------------------------------------
  416.           
  417. void rsc_treefix(OBJECT *tree);
  418.         
  419.         This function performs an rsrc_obfix() call for all objects in
  420.         a tree.  It's handy when using resource trees imbedded as source
  421.         code within your program, which require manual x/y fixup.  
  422.         
  423.         NOTE:  This functions uses the LASTOB bit in ob_flags to determine
  424.         when it has hit the end of the tree.  When coding your resource
  425.         tree, please be careful to set the LASTOB bit in the last object 
  426.         in the array.  Note that this is NOT a routine to provide a full
  427.         fixup of .RSH-type code emmitted by a resource construction editor;
  428.         this routine does only x/y/w/h fixup on a single tree, and does 
  429. |v1.4   not resolve cross-structure pointers.  (The C source code files
  430. |       RSHFIXUP.C and RS2FIXUP.C will provide the full runtime support for
  431. |       embedded resource files.  These are distributed separately from
  432. |       the GEMFAST package.)
  433.  
  434. ;*************************************************************************
  435. ;* Forms utilities.
  436. ;*************************************************************************
  437.  
  438. ;-------------------------------------------------------------------------
  439. ; frm_dsdial
  440. ;-------------------------------------------------------------------------
  441.  
  442. int  frm_dsdial(char *pstrings[], char *pbuttons[], int graphicsflag);
  443.                  
  444.         This function dynamically builds a dialog box around some
  445.         boilerplate text and displays it.  It is particularly useful for
  446.         displaying help screens, or for explaining a situation to the
  447.         user and providing a list of up to 5 choices/actions to be selected
  448.         via buttons (like a mega-sized alert box).
  449.         
  450.         The dialog box will be dynamically sized to hold as many as 20 lines
  451.         of text, and will adjust itself to the widest text line.  Up to 5
  452.         buttons may be specified, and the buttons will be centered at the
  453.         bottom of the dialog box.  The rightmost button (the last one 
  454.         specified) will always be the DEFAULT button.  It is the caller's
  455.         responsibility to insure that the widest text line (or the combined
  456.         length of the buttons) doesn't cause the dialog box to be wider 
  457.         than the current screen.  (EG, no auto-word-wrap here!)
  458.         
  459.         The routine returns the index of the button used to exit (first
  460. |       button == 0, etc), or -1 on error.  (Right now, the only way to 
  461. |       get -1 is to pass a NULL array pointer.)
  462.         
  463.         To specify the text lines and buttons, the caller passes pointers
  464.         to arrays of pointers to strings.  (This is not as complex as it
  465. |       sounds, see the example below.)  A pointer to a empty string or
  466. |       a NULL pointer terminate the lists of text and buttons.  (The
  467. |       use of a NULL pointer in an array slot as a terminator was added
  468. |       in v1.7).
  469.         
  470.         The caller also passes a TRUE/FALSE value for 'graphicsflag', to 
  471.         indicate whether FMD_GROW and FMD_SHRINK graphics should be done 
  472.         as part of the dialog processing.
  473.  
  474.         The following example shows setting up and calling this routine:
  475.         
  476.         char    *help1_screen[] = {
  477.             "            Help Screen 1",   /* title line, hand-centered */
  478.             "This is the first in a series of",
  479.             "help screens which tell you basically",
  480.             "nothing of true interest.  If you are",
  481.             "foolish enough to select the 'NEXT'",
  482.             "button, below, you will see even more",
  483.             "screens full of worthless information."
  484.             " ",                    /* 1 blank line between text & buttons */
  485.             ""};                    /* empty string terminates the list     */
  486.             
  487.         char    help1_buttons[] = {
  488.             "NEXT",
  489.             "DONE", 
  490.             NULL};                   /* NULL pointer terminates the list  */
  491.         int     btn;
  492.         
  493.         btn = frm_dsdial(help1_screen, help1_buttons, TRUE);
  494.         if (btn == 0) {
  495.             /* show second help screen */
  496.         } 
  497.  
  498.         While this routine can be incredibly useful in handling help text,
  499.         it should be noted that it is rather large.  After linking, it will
  500.         add about 1.5k to the size of your application (making it the largest
  501.         entity in the GEMFAST system).  
  502.  
  503. |v1.4   This routine is new with this release.
  504.  
  505. ;*************************************************************************
  506. ; Graphics Utilities.
  507. ;  These utilties are NOT available in C source code form, as they use
  508. ;  the Line-A TOS interface, which must be accessed via assembler code.
  509. ;*************************************************************************
  510.  
  511. ;-------------------------------------------------------------------------
  512. ; gra_qonmouse          (formerly graqon_mouse)
  513. ; gra_qofmouse          (formerly graqof_mouse)
  514. ;-------------------------------------------------------------------------
  515.  
  516. void graqon_mouse();
  517. void graqof_mouse();
  518.  
  519.         These routines turn the mouse pointer on and off quickly (using
  520.         the Line-A HideMouse/ShowMouse routines).  They will execute much
  521.         faster than the equivelant graf_mouse() calls, and they behave
  522. |v1.3   in a similar manner.  Specifically, the graf_mouse() calls track 
  523. |       the number of Hide/Show calls and if you 'hide' the mouse 3 times, 
  524. |       you must use the 'show' call 3 times before the mouse reappears.  
  525. |       These routines will behave in the same way (as of v1.3).  
  526.  
  527. ;-------------------------------------------------------------------------
  528. ; gra_qmstate           (formerly graq_mstate)
  529. ;-------------------------------------------------------------------------
  530.  
  531. graq_mstate(int *mousex, int *mousey, int *mousebtns);
  532.  
  533.         This routine returns the mouse x/y location and button state
  534.         quickly, using the Line-A variable structure as the source of 
  535.         information.  It is much faster than the graf_mkstate() call, and
  536.         it does not return the keyboard state information.  If you have
  537.         an application full of graf_mkstate() calls that don't use the
  538.         keystate info, you can code 
  539.           #define graf_mkstate(a,b,c,d) graq_mstate((a),(b),(c))
  540.         at the top of your program and instantly convert to the faster
  541.         routine.  (Caveat:  This routine is NOT well-tested in v1.0).
  542.         
  543. |v1.3   (NOTE:  I've had problems with using this routine in conjunction
  544. |       with evnt_mouse and evnt_multi type calls.  It seems that if you
  545. |       use the AES graf_mkstate() call it will (maybe?) clear some flag
  546. |       indicating a mouse-related event is pending.  When you use this
  547. |       Line-A routine, the event is left pending, and the next evnt_????
  548. |       call doesn't work as you'd expect.  I know, I know, I'm not being
  549. |       very clear; that's only because I haven't looked into it too 
  550. |       closely.  All I can say for sure is that some well-tested code
  551. |       broke when I #defined graf_mkstate to invoke this routine, and when
  552. |       I put it back, the code started working again.  Other code, however
  553. |       works just fine with graf_mkstate #define'd to this routine.- Ian)
  554.  
  555. ;*************************************************************************
  556. ;* End of doc.
  557. ;*************************************************************************
  558.  
  559.